package com.wang.springbootinit.service;

import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.baomidou.mybatisplus.extension.service.IService;
import com.wang.springbootinit.model.entity.Honor;
import com.wang.springbootinit.model.param.HonorParam;
import com.wang.springbootinit.model.vo.HonorVO;

import javax.servlet.http.HttpServletRequest;
import java.util.List;

/**
 * 荣誉服务接口
 * 定义荣誉模块的核心业务逻辑，包括荣誉申请、审核、查询等功能
 * 提供完整的荣誉管理生命周期支持
 *
 * @author wang
 */
public interface HonorService extends IService<Honor> {
    /**
     * 添加荣誉
     * 创建新的荣誉申请记录，设置初始状态为待审核
     * 需要校验必要字段（荣誉名称、级别、颁发单位）的完整性
     *
     * @param honor 荣誉信息，包含荣誉的基本信息
     * @return 新创建的荣誉ID
     * @throws BusinessException 当必要信息缺失时抛出参数错误异常
     */
    Long addHonor(HonorParam param);
    
    /**
     * 获取荣誉详情
     * 根据ID查询单条荣誉记录的完整信息
     *
     * @param id 荣誉ID
     * @return 荣誉详情对象，如果不存在返回null
     * @throws BusinessException 当ID参数无效时抛出参数错误异常
     */
    Honor getHonorById(Long id);
    
    /**
     * 获取学生的荣誉列表
     * 查询指定学生的所有荣誉记录
     * 支持按审核状态筛选，并按创建时间降序排序
     *
     * @param studentId 学生ID
     * @param status 审核状态（可选）：0-待审核，1-已通过，2-已拒绝
     * @return 荣誉列表
     * @throws BusinessException 当studentId无效时抛出参数错误异常
     */
    List<Honor> getStudentHonors(Long studentId, Integer status);
    
    /**
     * 分页获取荣誉列表
     * 支持多条件组合查询，包括：
     * - 按学生ID筛选
     * - 按荣誉级别筛选
     * - 按审核状态筛选
     * 结果按创建时间降序排序
     *
     * @param current 当前页码，从1开始
     * @param pageSize 每页显示记录数
     * @param studentNumber 学生ID（可选）
     * @param level 荣誉级别（可选）：校级、市级、省级、国家级
     * @param status 审核状态（可选）：0-待审核，1-已通过，2-已拒绝
     * @return 分页结果对象，包含总记录数和当前页数据
     */
    Page<HonorVO> listHonors(long current, long pageSize, String studentNumber, String level, Integer status);
    
    /**
     * 审核荣誉
     * 处理荣誉申请，更新审核状态和相关信息
     * 只有待审核状态的荣誉可以进行审核操作
     *
     * @param honor 包含审核结果的荣誉信息，必须包含ID和审核状态
     * @param request HTTP请求对象，用于获取当前审核人信息
     * @return 是否审核成功
     * @throws BusinessException 当参数无效、用户未登录或荣誉状态不正确时抛出相应异常
     */
    boolean auditHonor(Honor honor, HttpServletRequest request);
    
    /**
     * 统计各级别荣誉数量
     * 统计已通过审核的荣誉在不同级别的分布情况
     * 可以针对特定学生或所有学生进行统计
     *
     * @param studentId 学生ID（可选），如果提供则只统计该学生的荣誉
     * @return 统计结果列表，包含每个级别的荣誉数量，按数量降序排序
     */
    List<Honor> getHonorStatistics(Long studentId);

    /**
     * 获取学生参加的荣誉
     * @param request
     * @return
     */
    List<HonorVO> listHonors(HttpServletRequest request);

    /**
     * 学生本身添加荣誉
     * @param honor
     * @param request
     * @return
     */
    Boolean currentStudentApply(Honor honor, HttpServletRequest request);
}